Functions20

This section describes the functions an image decompressor component must include to use the base image decompressor.

ImageCodecBeginBand

The base image decompressor calls your image decompressor component's ImageCodecBeginBand function before drawing a band or frame. It allows your image decompressor component to save information about a band before decompressing it. Your component must implement this function.



 
pascal ComponentResult ImageCodecBeginBand (

                     ComponentInstance ci,

                     CodecDecompressParams *params,

                     ImageSubCodecDecompressRecord *drp,

                     long flags);

ci: Specifies the instance of the image decompressor component for the request.
params: Contains a pointer to a decompression parameters structure.
drp: Contains a pointer to a decompression record structure.
flags: Currently unused; always set to 0.

DISCUSSION

The base image decompressor never calls the ImageCodecBeginBand function at interrupt time.

You image decompressor component receives the address of the destination pixel map in the baseAddr field of the drp parameter. This address includes adjustment for the offset. Note that if the bit depth of the pixel map is less than 8, your image decompressor component must adjust for the bit offset.

The codecData field of the drp parameter contains a pointer to the compressed video data.

The userDecompressRecord field of the drp parameter contains a pointer to storage for the decompression operation. The storage is allocated by the base image decompressor after it calls the ImageCodecInitialize function. The size of the storage is determined by the decompressRecordSize field of the ImageSubCodecDecompressCapabilities structure that is returned by the ImageCodecInitialize function. Your image decompressor component should use this storage to store any additional information needed about the frame in order to decompress it.

Changes your image decompressor component makes to the ImageSubCodecDecompressRecord or CodecDecompressParams structures are preserved by the base image decompressor. For example, if your component does not need to decompress all of the data, it can change the pointer to the data to be decompressed that is stored in the codecData field of the ImageSubCodecDecompressRecord structure.

If your component supports asynchronous scheduled decompression, it may receive more than one ImageCodecBeginBand call before receiving an ImageCodecDrawBand call.

ImageCodecDrawBand

The base image decompressor calls your image decompressor component's ImageCodecDrawBand function to decompress a band or frame. Your component must implement this function.



 
pascal ComponentResult ImageCodecDrawBand (

                     ComponentInstance ci,

                     ImageSubCodecDecompressRecord *drp);

ci: Specifies the instance of the image decompressor component for the request.
drp: Contains a pointer to a decompression record structure.

DISCUSSION

If the ImageSubCodecDecompressRecord structure specifies a progress function or data-loading function, the base image decompressor never calls the ImageCodecDrawBand function at interrupt time. If not, the base image decompressor may call the ImageCodecDrawBand function at interrupt time.

When the base image decompressor calls your image decompressor component's ImageCodecDrawBand function, your component must perform the decompression specified by the fields of the ImageSubCodecDecompressRecord structure. The structure includes any changes your component made to it when performing the ImageCodecBeginBand function.

If your component supports asynchronous scheduled decompression, it may receive more than one ImageCodecBeginBand call before receiving an ImageCodecDrawBand call.

ImageCodecEndBand

The ImageCodecEndBand function notifies your image decompressor component that decompression of a band has finished or that it was terminated by the Image Compression Manager. Your image decompressor component is not required to implement the ImageCodecEndBand function.



 
pascal ComponentResult ImageCodecEndBand (

                     ComponentInstance ci,

                     ImageSubCodecDecompressRecord *drp,

                     OSErr result,

                     long flags);

ci: Specifies the instance of the image decompressor component for the request.
drp: Contains a pointer to a decompression record structure.
result: Contains a result code.
flags: Currently unused; must be set to 0.

DISCUSSION

The base image decompressor may call the ImageCodecEndBand function at interrupt time.

After your image decompressor component handles an ImageCodecEndBand call, it can perform any tasks that are required when decompression is finished, such as disposing of data structures that are no longer needed. Because this function can be called at interrupt time, your component cannot use this function to dispose of data structures; this must occur after handling the function.

The value of the result parameter is noErr if the band or frame was drawn successfully. If it is any other value, the band or frame was not drawn.

RESULT CODES

`noErr`	0	The band or frame was drawn successfully.
	-1	Drawing of the frame was cancelled in response to a call to `CDSequenceFlush.`
`codecAbortErr`	-8967	The operation was aborted by the progress function.

ImageCodecInitialize

The base image decompressor calls your image decompressor component's ImageCodecInitialize function before making any other all calls to your component.

Your component must implement this function. It responds by returning an ImageSubCodecDecompressCapabilities structure that specifies its capabilities.



 
pascal ComponentResult ImageCodecInitialize (

                     ComponentInstance ci, 

                     ImageSubCodecDecompressCapabilities *cap);

ci: Specifies the instance of the image decompressor component for the request.
cap: Specifies the capabilities of the image decompressor component.

DISCUSSION

TheImageSubCodecDecompressCapabilities structure that your component returns contains the following fields:

canAsync specifies whether your component can support asynchronous decompression operations, as described in "Asynchronous Decompression" (page 223) .
decompressRecordSize specifies the size of the decompression record structure for your component.

ImageCodecPreflight

The base image decompressor calls your image decompressor component's ImageCodecPreflight function before decompressing an image. It makes the call when responding to an ImageCodecPredecompress call from the Image Compression Manager.

Your component must implement this function. It responds by returning information about its capabilities in a compressor capabilities structure.



 
pascal ComponentResult ImageCodecPreflight (

                     ComponentInstance ci,

                     CodecDecompressParams *params);

ci: Specifies the instance of the image decompressor component for the request.
params: Contains a pointer to a decompression parameters structure.

DISCUSSION

The Image Compression Manager creates the decompression parameters structure, and your image decompressor component is required only to provide values for the wantedDestinationPixelSize and wantedDestinationPixelTypes fields of the structure. Your image decompressor component can also modify other fields if necessary. For example, if it can scale images, it must set the codecCapabilityCanScale flag in the capabilities field of the structure. See "The Compressor Capability Structure" (page 234) and "The Compressor Capability Structure" in Chapter 4 of Inside Macintosh: QuickTime Components for information about this structure.

ImageCodecQueueStarting

If your component supports asynchronous scheduled decompression, the base image decompressor calls your image decompressor component's ImageCodecQueueStarting function before decompressing the frames in the queue.

Your component is not required to implement this function. It can implement the function if it needs to perform any tasks at this time, such as locking data structures.



 
pascal ComponentResult ImageCodecQueueStarting (

                     ComponentInstance ci);

ci: Specifies the instance of the image decompressor component for the request.

DISCUSSION

The base image decompressor never calls the ImageCodecQueueStarting function at interrupt time.

ImageCodecQueueStopping

If your image decompressor component supports asynchronous scheduled decompression, the ImageCodecQueueStopping function notifies your component that the frames in the queue have been decompressed. Your component is not required to implement this function.



 
pascal ComponentResult ImageCodecQueueStopping (

                     ComponentInstance ci);

ci: Specifies the instance of the image decompressor component for the request.

DISCUSSION

The base image decompressor may call the ImageCodecQueueStopping function at interrupt time.

After your image decompressor component handles an ImageCodecQueueStopping call, it can perform any tasks that are required when decompression of the frames is finished, such as disposing of data structures that are no longer needed. Because this function can be called at interrupt time, your component cannot use this function to dispose of data structures; this must occur after handling the function.